Настройка синхронизации пользователей из ALD Pro в Keycloak
-----------------------------------------------------------

Основная настройка Keycloak подробно описана на официальном сайте Keycloak. В данной инструкции описано создание Федерации пользователей (User federation) с пользователями ALD Pro.

Термины и определения
~~~~~~~~~~~~~~~~~~~~~

- Федерация пользователей - синхронизация пользователей с сервером ALD Pro;
- Single Sign-On - SSO - метод аутентификации, который позволяет пользователям безопасно аутентифицироваться сразу в нескольких приложениях и сайтах, используя один набор учетных данных.

Предварительная настройка ALD Pro
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Создание пользователя
^^^^^^^^^^^^^^^^^^^^^

В ALD Pro необходимо создать пользователя (рисунок 1), через которого будет осуществляться синхронизация пользователей, групп, подразделений. В целях безопасности пользователь не должен обладать правами администратора. Для синхронизации пользователей достаточно прав обычного пользователя.

.. figure:: media/1.png
   :name: 1

Активация пользователя
^^^^^^^^^^^^^^^^^^^^^^

Перед дальнейшей работы, следует авторизоваться под созданным пользователем и сменить ему пароль.

Краткая инструкция настройки Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _tab:criteria:
.. list-table::
   :widths: 20 80
   :header-rows: 1
   :class: longtable
   :name: Настройки Keycloak

   * - Наименование
     - Значение
   * - **Hostname**
     - astralinux.ru
   * - **URI/Port**
     - ldap://astralinux.ru.ru:389 (_STARTTLS_) **Note**: Plaintext is not allowed.
   * - 
     - ldaps://astralinux.ru:636
   * - **BaseDN**
     - uid=_ALD_user_,cn=users,cn=_accounts_,dc=astralinux,dc=ru
   * - **UserDN**
     - cn=users,cn=_accounts_,dc=astralinux,dc=ru
   * - **GroupDN**
     - ou=users,o=_YOUR_ORG_ID_,dc=jumpcloud,dc=com
   * - Username LDAP attribute, RDN LDAP attribute
     - uid
   * - **UID LDAP attribute**
     - ipaUniqueId
   * - **Search scope**
     - One level

Подробная инструкция настройки Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Приведенная ниже инструкция актуальна для Keycloak Version 23.0.3

Создание User Federation c ALD Pro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Создание User Federation
''''''''''''''''''''''''

1. Выполнен вход в Keycloak c правами администратора и создан рабочий Realm.

2. На вкладке “User federation” выбран “Add Ldap providers”, во всплывающем окне выбран “LDAP” (рисунок 2).

.. figure:: media/2.png
   :name: 2

Заполнение блока General options
''''''''''''''''''''''''''''''''

3. В открывшемся окне заполнены обязательные поля (рисунок 3).

4. В качестве вендора выбран “Other” или “Red Hat Directory Server”. В дальнейшем вендора для созданной федерации пользователя изменить нельзя.

5. Connection URL: URL-адрес подключения ALD Pro в формате: ldap://astralinux.ru:389

6. Остальные настройки остаются на усмотрение.

.. figure:: media/3.png
   :name: 3

Заполнение блока Connection and authentication settings
'''''''''''''''''''''''''''''''''''''''''''''''''''''''

7. Тип связи (Bind type) выбран простой (simple).

8. В “Bind DN” указан путь навигации к созданному ранее пользователю ALD Pro. DN записывается слева направо.

9. В “Bind credentials” указан пароль от привязанного пользователя ALD Pro.

.. figure:: media/4.png
   :name: 4

Тест соединения и аутентификации
''''''''''''''''''''''''''''''''

На этом этапе можно проверить успешность заполнения форм, нажав последовательно на “Test connection” и “Test authentication” (рисунок 5).

.. figure:: media/5.png
   :name: 5

При успешном соединении и аутентификации пользователей появятся сообщения об успешном завершении операции (рисунок 6).

.. figure:: media/6.png
   :name: 6

Заполнение блока LDAP searching and updating
''''''''''''''''''''''''''''''''''''''''''''

10. Режим редактирования (Edit mode) выбран “READ_ONLY”.

11. Указан путь навигации к пользователям (User DN) сервера ALD Pro.

12. Атрибуты “Username LDAP” и “RDN LDAP” - “uid”.

13. “UUID LDAP” - “ipaUniqueId”.

14. Поле “User object classes” можно оставить по умолчанию.

15. В целях безопасности каталога ALD Pro, по желанию, можно указать фильтры синхронизации для пользователей.

16. Область поиска (Search scope) для ALD Pro - “One Level”.

17. Параметры тайм-аут чтения (Read timeout) и пагинация (Pagination) - на усмотрение.

Пример заполнения на рисунке 7.

.. figure:: media/7.png
   :name: 7

Заполнение блока Synchronization settings
'''''''''''''''''''''''''''''''''''''''''

18. Для настройки импорта пользователей слайдер Import users находится в положении ON.

19. Если пользователей много, рекомендуется при их импорте разбивать их на партии с помощью настройки размера партии (Batch size).

20. Для полной и периодической синхронизации пользователей рекомендуется настроить время синхронизации с помощью параметров (Periodic full sync, Periodic changed users syn). Значения указываются в секундах.

.. figure:: media/8.png
   :name: 8

Заполнение блоков Kerberos integration, Cache settings, Advanced settings
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Остальные параметры настраиваются индивидуально и позволяют гибко управлять синхронизацией и безопасностью единого входа с помощью федерации пользователей.

Проверка синхронизации пользователей
''''''''''''''''''''''''''''''''''''

21. При завершении настроек сохранить федерацию пользователей. После сохранения федерация появится на вкладке “User federation” (рисунок 9).

.. figure:: media/9.png
   :name: 9

22. Выполнить переход на вкладку пользователи, здесь находятся все пользователи Realm, включая пользователей федерации. Иногда в настройках Keycloak для оптимизации работы на вкладке пользователи не отображаются пользователи федерации. Для того чтобы увидеть всех пользователей нужно в поиске ввести \* и выполнить поиск.

Настройка соответствия атрибутов
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Атрибуты пользователей keycloak не полностью соответствуют атрибутам ALD Pro. В таблице приведены основные соответствия атрибутов ALD Pro к Keycloak.

.. _tab:criteria:
.. list-table::
   :widths: auto
   :header-rows: 1
   :class: longtable
   :name: Соответствия атрибутов ALD Pro к Keycloak

   * - Keycloak
     - ALD Pro
     - Mapper type
   * - email
     - mail
     - user-attribute-ldap-mapper
   * - firstName
     - givenName
     - user-attribute-ldap-mapper

Синхронизация групп пользователей из ALD Pro в Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Настройка mapper в User federation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Для синхронизации пользователь должен обладать правами на чтение групп пользователей.

1. Выбрать ldap для которой нужно синхронизировать группы (рисунок 10).

.. figure:: media/10.png
   :name: 10

2. На странице “Mappers” необходимо создать новое соответствие (рисунок 11).

.. figure:: media/11.png
   :name: 11

3. Для создания правильного mapper необходимо заполнить следующие поля:

.. _tab:criteria:
.. list-table::
   :widths: 30 70
   :header-rows: 1
   :class: longtable
   :name: Поля, обязательные для заполнения

   * - Поле
     - Значение
   * - Name
     - <название mapper>
   * - Mapper type
     - group-ldap-mapper
   * - LDAP Groups DN (в соответствии с примером по созданию федерации пользователя)
     - cn=groups,cn=accounts,dc=astralinux,dc=ru
   * - User Groups Retrieve Strategy
     - ``GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE``

Остальные поля возможно оставить в значении по умолчанию.

Настройка Client scope
^^^^^^^^^^^^^^^^^^^^^^

1. На вкладке “Client Scopes” выбран “Create client scope”.

2. Параметр имя - “Groups”. Остальные по умолчанию. Сохранить.

3. Настройка mapper для этого “Client Scopes” (рисунок 12, 13).

.. figure:: media/12.png
   :name: 12

.. figure:: media/13.png
   :name: 13

7. mapper заполнен в соответствии с рисунком 14.

.. figure:: media/14.png
   :name: 14

На данном шаге настройка синхронизации пользователей и групп из ALD Pro завершена.

Синхронизация подразделений
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Создание mapper
^^^^^^^^^^^^^^^

Для синхронизации подразделений сервисный пользователь должен обладать правами на просмотр подразделений.

В Keycloak из коробки нет такой сущности как подразделение, но возможна синхронизация через сущность “группы”.

1. Выполнен переход в карточку “User Federation”.

.. figure:: media/15.png
   :name: 15

2. Во вкладке “Mappers” добавлен mapper (рисунок 16).

.. figure:: media/16.png
   :name: 16

3. Для создания правильного mapper необходимо заполнить следующие поля:

.. _tab:criteria:
.. list-table::
   :widths: 30 70
   :header-rows: 1
   :class: longtable
   :name: Поля, обязательные для заполнения 2

   * - Поле
     - Значение
   * - Name
     - <название mapper>
   * - Mapper type
     - group-ldap-mapper
   * - LDAP Groups DN (в соответствии с примером по созданию федерации пользователя)
     - ou=astralinux.ru,cn=orgunits,cn=accounts,dc=astralinux,dc=ru
   * - Group Name LDAP Attribute
     - ou
   * - Group Object Classes
     - rbta-org-unit
   * - Member-Of LDAP Attribute
     - rbtadp
   * - User Groups Retrieve Strategy
     - ``GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE``

Остальные поля остаются в значении по умолчанию.

Для корректной работы протоколов может понадобиться `настройка Keycloak. <https://freeipa.readthedocs.io/en/latest/workshop/12-external-idp-support.html>`__
